/***************************************************************
 *  Copyright (c) 2007 by GroupMe! Team (www.groupme.net)
 *  All rights reserved
 *
 *  This file is part of the GroupMe! Project. You can utilize
 *  software of the GroupMe! project under the terms of the 
 *  GNU Lesser General Public License as published by the
 *  Free Software Foundation in version 2.1.
 * 
 *  The GNU Lesser General Public License can be found at:
 *  http://www.gnu.org/licenses/lgpl.html
 *
 *  This copyright notice MUST APPEAR in all copies of the file!
 ***************************************************************/
package net.groupme.model;

import java.util.Collection;
import java.sql.Date;

import net.groupme.exceptions.DeleteFailedException;
import net.groupme.exceptions.InsertFailedException;
import net.groupme.exceptions.UpdateFailedException;

/**
 * 
 * This interface defines defines the Tag object in the GroupMe! project. A Tag
 * object tags Resource objects {@link net.groupme.model.Resource}.
 * 
 * @author Mischa Frank, <a
 *         href="mailto:code@planetfrank.net">code@planetfrank.net</a>
 * 
 * @version 0.1a, created on 30.04.2007
 * 
 */
public interface Tag extends Identifiable {

	/**
	 * This method adds the Tag to a Resource in a Group by a User with a
	 * priority.
	 * 
	 * @param resource
	 * @param user
	 * @param group
	 * @param date
	 * @param importance
	 * @throws InsertFailedException
	 */
	public void add(Resource resource, User user, Group group, Date date,
			double importance) throws InsertFailedException;

	/**
	 * This method returns the keyword of the Tag.
	 * 
	 * @return Keyword of the Tag.
	 */
	public String getKeyword();

	/**
	 * This method returns all Resource object which are tagged by this Tag.
	 * 
	 * @return Collection of Resource objects which are tagged by this tag
	 */
	public Collection<Resource> getResources();

	/**
	 * This method returns all Resource objects which are tagged by the Tag from
	 * a given User.
	 * 
	 * @param tagger/User
	 * @return Collection of Resource objects tagged by this Tag from a User
	 */
	public Collection<Resource> getResources(User tagger);

	/**
	 * This method returns all Resource objects tagged with this Tag in a given
	 * Group by a given User.
	 * 
	 * @param user
	 * @param group
	 */
	public Collection<Resource> getResources(User user, Group group);

	/**
	 * Thsi method returns those users who have tagged a given resource with this {@link Tag} instance.
	 * 
	 * @param a resource which should be tagged by this tag
	 * @return users who have tagged a given resource with this {@link Tag} instance.
	 */
	public Collection<User> getUsers(Resource resource);
	
	/**
	 * This method removes a Tag from a Resource and a Group for a User.
	 * 
	 * @param resource
	 * @param user
	 * @param group
	 * @throws DeleteFailedException
	 */
	public void remove(Resource resource, User user, Group group)
			throws DeleteFailedException;
	
	/**
	 * This method sets the Keyword of the Tag.
	 * 
	 * @param keyword
	 * @throws UpdateFailedException 
	 */
	public void setKeyword(String keyword) throws UpdateFailedException;
}
